<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!--

Generated from manual.tex by tex2page, v 20050501
(running on MzScheme 369.1, unix), 
(c) Dorai Sitaram, 
http://www.ccs.neu.edu/~dorai/tex2page/tex2page-doc.html

-->
<head>
<title>
The Incomplete Scheme 48 Reference Manual for release 1.4
</title>
<link rel="stylesheet" type="text/css" href="manual-Z-S.css" title=default>
<meta name=robots content="noindex,follow">
</head>
<body>
<div id=content>
<div align=right class=navigation><i>[Go to <span><a href="manual.html">first</a>, <a href="manual-Z-H-9.html">previous</a></span><span>, <a href="manual-Z-H-11.html">next</a></span> page<span>; &nbsp;&nbsp;</span><span><a href="manual-Z-H-2.html#node_toc_start">contents</a></span><span><span>; &nbsp;&nbsp;</span><a href="manual-Z-H-13.html#node_index_start">index</a></span>]</i></div>
<p></p>
<a name="node_chap_8"></a>
<h1 class=chapter>
<div class=chapterheading><a href="manual-Z-H-2.html#node_toc_node_chap_8">Chapter 8</a></div><br>
<a href="manual-Z-H-2.html#node_toc_node_chap_8">Access to POSIX</a></h1>
<p>This chapter describes Scheme&nbsp;48's interface to the POSIX C calls
[<a href="manual-Z-H-12.html#node_bib_1">1</a>].
Scheme versions of most of the functions in POSIX are provided.
Both the interface and implementation are new and are likely to
change in future releases.
Section&nbsp;<a href="#node_sec_8.10">8.10</a> lists which Scheme functions
call which C functions.</p>
<p>
Scheme&nbsp;48's POSIX interface will likely change significantly in the
future.
The implementation is new and may have significant bugs.</p>
<p>
The POSIX bindings are available in several structures:</p>
<p>
</p>
<div align=center><table><tr><td>

<table border=0><tr><td valign=top ><tt>posix-processes</tt> </td><td valign=top >fork, exec, and friends </td></tr>
<tr><td valign=top ><tt>posix-process-data</tt> </td><td valign=top >information about processes </td></tr>
<tr><td valign=top ><tt>posix-files</tt> </td><td valign=top >files and directories </td></tr>
<tr><td valign=top ><tt>posix-i/o</tt> </td><td valign=top >operations on ports </td></tr>
<tr><td valign=top ><tt>posix-time</tt> </td><td valign=top >time functions </td></tr>
<tr><td valign=top ><tt>posix-users</tt> </td><td valign=top >users and groups </td></tr>
<tr><td valign=top ><tt>posix-regexps</tt> </td><td valign=top >regular expression matching </td></tr>
<tr><td valign=top ><tt>posix</tt> </td><td valign=top >all of the above
</td></tr></table>
</td></tr></table></div>
<p>
Scheme&nbsp;48's POSIX interface differs from
Scsh's [<a href="manual-Z-H-12.html#node_bib_11">11</a>,&nbsp;<a href="manual-Z-H-12.html#node_bib_12">12</a>] in several ways.
The interface here lacks Scsh's high-level constructs and utilities,
such as the process notation, <tt>awk</tt> procedure, and parsing
utilities.
Scheme&nbsp;48 uses distinct types for some values that Scsh leaves
as symbols or unboxed integers; these include file types, file modes,
and user and group ids.
Many of the names and other interface details are different, as well.</p>
<p>
</p>
<a name="node_sec_8.1"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.1">8.1&nbsp;&nbsp;Process primitives</a></h2>
<p>The procedures described in this section control the creation of processes
and the execution of programs.
They are in the structures <tt>posix-process</tt> and <tt>posix</tt>.</p>
<p>
</p>
<a name="node_sec_8.1.1"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.1.1">8.1.1&nbsp;&nbsp;Process creation and termination</a></h3>
<p></p>
<p>
</p>
<ul>
<li><p><tt>(fork<i></i>)&nbsp;-&gt;&nbsp;<i>process-id or <tt>#f</tt></i></tt><a name="node_idx_606"></a>
</p>
<li><p><tt>(fork-and-forget<i> thunk</i>)</tt><a name="node_idx_608"></a>
</p>
</ul><p>
<tt>Fork</tt> creates a new child process and returns the child's process-id in
the parent and <tt>#f</tt> in the child.
<tt>Fork-and-forget</tt> calls <i>thunk</i> in a new process; no process-id
is returned.
<tt>Fork-and-forget</tt> uses an intermediate process to avoid creating
a zombie process.</p>
<p>
</p>
<ul>
<li><p><tt>(process-id?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_610"></a>
</p>
<li><p><tt>(process-id=?<i> process-id0 process-id1</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_612"></a>
</p>
<li><p><tt>(process-id-&gt;integer<i> process-id</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_614"></a>
</p>
<li><p><tt>(integer-&gt;process-id<i> integer</i>)&nbsp;-&gt;&nbsp;<i>process-id</i></tt><a name="node_idx_616"></a>
</p>
</ul><p>
<tt>Process-id?</tt> is a predicate for process-ids,
<tt>process-id=?</tt> compares two to see if they are the same,
and <tt>process-id-uid</tt> returns the actual Unix id.
<tt>Process-id-&gt;integer</tt> and <tt>integer-&gt;process-id</tt>
convert process ids to and from integers.</p>
<p>
</p>
<ul>
<li><p><tt>(process-id-exit-status<i> process-id</i>)&nbsp;-&gt;&nbsp;<i>integer or <tt>#f</tt></i></tt><a name="node_idx_618"></a>
</p>
<li><p><tt>(process-id-terminating-signal<i> process-id</i>)&nbsp;-&gt;&nbsp;<i>signal or <tt>#f</tt></i></tt><a name="node_idx_620"></a>
</p>
<li><p><tt>(wait-for-child-process<i> process-id</i>)</tt><a name="node_idx_622"></a>
</p>
</ul><p>
If a process terminates normally
<tt>process-id-exit-status</tt> will return its exit status.
If the process is still running or was terminated by a signal then
<tt>process-id-exit-status</tt> will return <tt>#f</tt>.
Similarly, if a child process was terminated by a signal
<tt>process-id-terminating-signal</tt> will return that signal and
will return <tt>#f</tt> if the process is still running or terminated
normally.
<tt>Wait-for-child-process</tt> blocks until the child process terminates.
Scheme&nbsp;48 may reap child processes before the user requests their
exit status, but it does not always do so.</p>
<p>
</p>
<ul>
<li><p><tt>(exit<i> status</i>)</tt><a name="node_idx_624"></a>
</p>
</ul><p>
Terminates the current process with the integer <i>status</i>
as its exit status.</p>
<p>
</p>
<a name="node_sec_8.1.2"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.1.2">8.1.2&nbsp;&nbsp;<tt>Exec</tt></a></h3>
<p></p>
<ul>
<li><p><tt>(exec<i> program-name arg0 <tt>...</tt></i>)</tt><a name="node_idx_626"></a>
</p>
<li><p><tt>(exec-with-environment<i> program-name env arg0 <tt>...</tt></i>)</tt><a name="node_idx_628"></a>
</p>
<li><p><tt>(exec-file<i> filename arg0 <tt>...</tt></i>)</tt><a name="node_idx_630"></a>
</p>
<li><p><tt>(exec-file-with-environment<i> filename env arg0 <tt>...</tt></i>)</tt><a name="node_idx_632"></a>
</p>
<li><p><tt>(exec-with-alias<i> name lookup? maybe-env arguments</i>)</tt><a name="node_idx_634"></a>
</p>
</ul><p>
All of these replace the current program with a new one.
They differ in how the new program is found, what its environment is,
and what arguments it is passed.
<tt>Exec</tt> and <tt>exec-with-environment</tt>
look up the new program in the search path,
while <tt>exec-file</tt> and <tt>exec-file-with-environment</tt>
execute a particular file.
The environment is either inherited from the current process
(<tt>exec</tt> and <tt>exec-file</tt>) or given as an argument
(<tt><tt>...</tt>-with-environment</tt>).
<i>Program-name</i> and <i>filename</i> and any <i>arg<sub><em>i</em></sub></i> should be strings.
<i>Env</i> should be a list of strings of the form
<tt>&quot;<i>name</i>=<i>value</i>&quot;</tt>.
The first four procedures add their first argument, <i>program-name</i> or
<i>filename</i>, before the <i>arg0 <tt>...</tt></i> arguments.</p>
<p>
<tt>Exec-with-alias</tt> is an omnibus procedure that subsumes the other
four.
<i>Name</i> is looked up in the search path if <i>lookup?</i> is true
and is used as a filename otherwise.
<i>Maybe-env</i> is either a list of strings for the environment of the
new program or <tt>#f</tt> in which case the new program inherits its
environment from the current one.
<i>Arguments</i> should be a list of strings; unlike with the other four
procedures, <i>name</i> is not added to this list (hence <tt>-with-alias</tt>).</p>
<p>
</p>
<a name="node_sec_8.2"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.2">8.2&nbsp;&nbsp;Signals</a></h2>
<p>There are two varieties of signals available, <em>named</em> and <em>anonymous</em>.
A named signal is one for which we have a symbolic name, such as <tt>kill</tt>
or <tt>pipe</tt>.  
Anonymous signals, for which we only have the current operating system's
signal number, have no meaning in other operating systems.
Named signals preserve their meaning in image files.
Not all named signals are available from all OS's and
there may be multiple names for a single OS signal number.</p>
<p>
</p>
<ul>
<li><p><tt>(signal <i>signal-name</i>)&nbsp;-&gt;&nbsp;<i>signal</i></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(syntax)
</p>
<li><p><tt>(name-&gt;signal<i> symbol</i>)&nbsp;-&gt;&nbsp;<i>signal or <tt>#f</tt></i></tt><a name="node_idx_636"></a>
</p>
<li><p><tt>(integer-&gt;signal<i> integer</i>)&nbsp;-&gt;&nbsp;<i>signal</i></tt><a name="node_idx_638"></a>
</p>
<li><p><tt>(signal?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_640"></a>
</p>
<li><p><tt>(signal-name<i> signal</i>)&nbsp;-&gt;&nbsp;<i>symbol or <tt>#f</tt></i></tt><a name="node_idx_642"></a>
</p>
<li><p><tt>(signal-os-number<i> signal</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_644"></a>
</p>
<li><p><tt>(signal=?<i> signal0 signal1</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_646"></a>
</p>
</ul><p>
The syntax <tt>signal</tt> returns a (named) signal associated with
<i>signal-name</i>.
<tt>Name-&gt;signal</tt> returns a (named) signal or <tt>#f</tt> if the
the signal <i>name</i> is not supported by the operating system.
The signal returned by <tt>integer-&gt;signal</tt> is a named signal if
<i>integer</i> corresponds to a named signal in the current operating
system; otherwise it returns an anonymous signal.
<tt>Signal-name</tt> returns a symbol if <i>signal</i> is named and
<tt>#f</tt> if it is anonymous. 
<tt>Signal=?</tt> returns <tt>#t</tt> if <i>signal0</i> and <i>signal1</i>
have the same operating system number and <tt>#f</tt> if they do not.</p>
<p>
</p>
<a name="node_sec_8.2.1"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.2.1">8.2.1&nbsp;&nbsp;POSIX signals</a></h3>
<p>The following lists the names of the POSIX signals.
</p>
<div align=center><table><tr><td>

<table border=0><tr><td valign=top ><tt>abrt</tt> </td><td valign=top >abort - abnormal termination (as by abort()) </td></tr>
<tr><td valign=top ><tt>alrm</tt> </td><td valign=top >alarm - timeout signal (as by alarm()) </td></tr>
<tr><td valign=top ><tt>fpe </tt> </td><td valign=top >floating point exception </td></tr>
<tr><td valign=top ><tt>hup </tt> </td><td valign=top >hangup - hangup on controlling terminal or death of
controlling process </td></tr>
<tr><td valign=top ><tt>ill </tt> </td><td valign=top >illegal instruction </td></tr>
<tr><td valign=top ><tt>int </tt> </td><td valign=top >interrupt - interaction attention </td></tr>
<tr><td valign=top ><tt>kill</tt> </td><td valign=top >kill - termination signal, cannot be caught or ignored </td></tr>
<tr><td valign=top ><tt>pipe</tt> </td><td valign=top >pipe - write on a pipe with no readers </td></tr>
<tr><td valign=top ><tt>quit</tt> </td><td valign=top >quit - interaction termination </td></tr>
<tr><td valign=top ><tt>segv</tt> </td><td valign=top >segmentation violation - invalid memory reference </td></tr>
<tr><td valign=top ><tt>term</tt> </td><td valign=top >termination - termination signal </td></tr>
<tr><td valign=top ><tt>usr1</tt> </td><td valign=top >user1 - for use by applications </td></tr>
<tr><td valign=top ><tt>usr2</tt> </td><td valign=top >user2 - for use by applications </td></tr>
<tr><td valign=top ><tt>chld</tt> </td><td valign=top >child - child process stopped or terminated </td></tr>
<tr><td valign=top ><tt>cont</tt> </td><td valign=top >continue - continue if stopped </td></tr>
<tr><td valign=top ><tt>stop</tt> </td><td valign=top >stop - cannot be caught or ignored </td></tr>
<tr><td valign=top ><tt>tstp</tt> </td><td valign=top >interactive stop </td></tr>
<tr><td valign=top ><tt>ttin</tt> </td><td valign=top >read from control terminal attempted by background process </td></tr>
<tr><td valign=top ><tt>ttou</tt> </td><td valign=top >write to control terminal attempted by background process </td></tr>
<tr><td valign=top ><tt>bus </tt> </td><td valign=top >bus error - access to undefined portion of memory </td></tr>
<tr><td valign=top ></td></tr></table>
</td></tr></table></div>
<p>
</p>
<a name="node_sec_8.2.2"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.2.2">8.2.2&nbsp;&nbsp;Other signals</a></h3>
<p>The following lists the names of the non-POSIX signals that the system is
currently aware of.
</p>
<div align=center><table><tr><td>

<table border=0><tr><td valign=top ><tt>trap  </tt> </td><td valign=top >trace or breakpoint trap </td></tr>
<tr><td valign=top ><tt>iot   </tt> </td><td valign=top >IOT trap - a synonym for ABRT </td></tr>
<tr><td valign=top ><tt>emt   </tt> </td><td valign=top ></td></tr>
<tr><td valign=top ><tt>sys   </tt> </td><td valign=top >bad argument to routine (SVID) </td></tr>
<tr><td valign=top ><tt>stkflt</tt> </td><td valign=top >stack fault on coprocessor </td></tr>
<tr><td valign=top ><tt>urg   </tt> </td><td valign=top >urgent condition on socket      (4.2 BSD) </td></tr>
<tr><td valign=top ><tt>io    </tt> </td><td valign=top >I/O now possible                (4.2 BSD) </td></tr>
<tr><td valign=top ><tt>poll  </tt> </td><td valign=top >A synonym for SIGIO             (System V) </td></tr>
<tr><td valign=top ><tt>cld   </tt> </td><td valign=top >A synonym for SIGCHLD </td></tr>
<tr><td valign=top ><tt>xcpu  </tt> </td><td valign=top >CPU time limit exceeded (4.2 BSD) </td></tr>
<tr><td valign=top ><tt>xfsz  </tt> </td><td valign=top >File size limit exceeded        (4.2 BSD) </td></tr>
<tr><td valign=top ><tt>vtalrm</tt> </td><td valign=top >Virtual alarm clock             (4.2 BSD) </td></tr>
<tr><td valign=top ><tt>prof  </tt> </td><td valign=top >Profile alarm clock </td></tr>
<tr><td valign=top ><tt>pwr   </tt> </td><td valign=top >Power failure                   (System V) </td></tr>
<tr><td valign=top ><tt>info  </tt> </td><td valign=top >A synonym for SIGPWR </td></tr>
<tr><td valign=top ><tt>lost  </tt> </td><td valign=top >File lock lost </td></tr>
<tr><td valign=top ><tt>winch </tt> </td><td valign=top >Window resize signal            (4.3 BSD, Sun) </td></tr>
<tr><td valign=top ><tt>unused</tt> </td><td valign=top >Unused signal </td></tr>
<tr><td valign=top ></td></tr></table></td></tr></table></div>
<p>
</p>
<a name="node_sec_8.2.3"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.2.3">8.2.3&nbsp;&nbsp;Sending signals</a></h3>
<p></p>
<ul>
<li><p><tt>(signal-process<i> process-id signal</i>)</tt><a name="node_idx_648"></a>
</p>
</ul><p>
Send <i>signal</i> to the process corresponding to <i>process-id</i>.</p>
<p>
</p>
<a name="node_sec_8.2.4"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.2.4">8.2.4&nbsp;&nbsp;Receiving signals</a></h3>
<p>Signals received by the Scheme process can be obtained via one or more
signal-queues.
Each signal queue has a list of monitored signals and a queue of
received signals that have yet to be read from the signal-queue.
When the Scheme process receives a signal that signal is added to the
received-signal queues of all signal-queues which are currently monitoring
that particular signal.</p>
<p>
</p>
<ul>
<li><p><tt>(make-signal-queue<i> signals</i>)&nbsp;-&gt;&nbsp;<i>signal-queue</i></tt><a name="node_idx_650"></a>
</p>
<li><p><tt>(signal-queue?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_652"></a>
</p>
<li><p><tt>(signal-queue-monitored-signals<i> signal-queue</i>)&nbsp;-&gt;&nbsp;<i>list of signals</i></tt><a name="node_idx_654"></a>
</p>
<li><p><tt>(dequeue-signal!<i> signal-queue</i>)&nbsp;-&gt;&nbsp;<i>signal</i></tt><a name="node_idx_656"></a>
</p>
<li><p><tt>(maybe-dequeue-signal!<i> signal-queue</i>)&nbsp;-&gt;&nbsp;<i>signal or <tt>#f</tt></i></tt><a name="node_idx_658"></a>
</p>
</ul><p>
<tt>Make-signal-queue</tt> returns a new signal-queue that will monitor
the signals in the list <i>signals</i>.
<tt>Signal-queue?</tt> is a predicate for signal queues.
<tt>Signal-queue-monitored-signals</tt> returns a list of the signals
currently monitored by <i>signal-queue</i>.
<tt>Dequeue-signal!</tt> and <tt>maybe-dequeue-signal</tt> both return
the next received-but-unread signal from <i>signal-queue</i>.
If <i>signal-queue</i>'s queue of signals is empty <tt>dequeue-signal!</tt>
blocks until an appropriate signal is received.
<tt>Maybe-dequeue-signal!</tt> does not block; it returns <tt>#f</tt> instead.</p>
<p>
There is a bug in the current system that causes an erroneous deadlock
error if threads are blocked waiting for signals and no other threads
are available to run.
A work around is to create a thread that sleeps for a long time, which
prevents any deadlock errors (including real ones):
</p>
<pre class=verbatim>&gt; ,open threads
&gt; (spawn (lambda ()
           ; Sleep for a year
           (sleep (* 1000 60 60 24 365))))
</pre><p></p>
<p>
</p>
<ul>
<li><p><tt>(add-signal-queue-signal!<i> signal-queue signal</i>)</tt><a name="node_idx_660"></a>
</p>
<li><p><tt>(remove-signal-queue-signal!<i> signal-queue signal</i>)</tt><a name="node_idx_662"></a>
</p>
</ul><p>
These two procedures can be used to add or remove signals from a
signal-queue's list of monitored signals.
When a signal is removed from a signal-queue's list of monitored signals
any occurances of the signal are removed from that signal-queue's pending
signals.
In other words, <tt>dequeue-signal!</tt> and <tt>maybe-dequeue-signal!</tt>
will only return signals that are currently on the signal-queue's list
of signals.</p>
<p>
</p>
<a name="node_sec_8.3"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.3">8.3&nbsp;&nbsp;Process environment</a></h2>
<p>These are in structures <tt>posix-process-data</tt> and <tt>posix</tt>.</p>
<p>
</p>
<a name="node_sec_8.3.1"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.3.1">8.3.1&nbsp;&nbsp;Process identification</a></h3>
<p></p>
<ul>
<li><p><tt>(get-process-id<i></i>)&nbsp;-&gt;&nbsp;<i> process-id</i></tt><a name="node_idx_664"></a>
</p>
<li><p><tt>(get-parent-process-id<i></i>)&nbsp;-&gt;&nbsp;<i> process-id</i></tt><a name="node_idx_666"></a>
</p>
</ul><p>
These return the process ids of the current process and its parent.
See section&nbsp;<a href="#node_sec_8.1.1">8.1.1</a> for operations on process ids.</p>
<p>
</p>
<ul>
<li><p><tt>(get-user-id<i></i>)&nbsp;-&gt;&nbsp;<i> user-id</i></tt><a name="node_idx_668"></a>
</p>
<li><p><tt>(get-effective-user-id<i></i>)&nbsp;-&gt;&nbsp;<i> user-id</i></tt><a name="node_idx_670"></a>
</p>
<li><p><tt>(set-user-id!<i> user-id</i>)</tt><a name="node_idx_672"></a>
</p>
</ul><p></p>
<p>
</p>
<ul>
<li><p><tt>(get-group-id<i></i>)&nbsp;-&gt;&nbsp;<i> group-id</i></tt><a name="node_idx_674"></a>
</p>
<li><p><tt>(get-effective-group-id<i></i>)&nbsp;-&gt;&nbsp;<i> group-id</i></tt><a name="node_idx_676"></a>
</p>
<li><p><tt>(set-group-id!<i> group-id</i>)</tt><a name="node_idx_678"></a>
</p>
</ul><p>
Every process has both the original and effective user id and group id.
The effective values may be set, but not the original ones.</p>
<p>
</p>
<ul>
<li><p><tt>(get-groups<i></i>)&nbsp;-&gt;&nbsp;<i> group-ids</i></tt><a name="node_idx_680"></a>
</p>
<li><p><tt>(get-login-name<i></i>)&nbsp;-&gt;&nbsp;<i> string</i></tt><a name="node_idx_682"></a>
</p>
</ul><p>
<tt>Get-groups</tt> returns a list of the supplementary groups of the
current process.
<tt>Get-login-name</tt> returns a user name for the current process.</p>
<p>
</p>
<p>
</p>
<p>
</p>
<a name="node_sec_8.3.2"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.3.2">8.3.2&nbsp;&nbsp;Environment variables</a></h3>
<p></p>
<ul>
<li><p><tt>(lookup-environment-variable<i> string</i>)&nbsp;-&gt;&nbsp;<i>string or <tt>#f</tt></i></tt><a name="node_idx_684"></a>
</p>
<li><p><tt>(environment-alist<i></i>)&nbsp;-&gt;&nbsp;<i>alist</i></tt><a name="node_idx_686"></a>
</p>
</ul><p>
<tt>Lookup-environment-variable</tt> looks up its argument in the
environment list and returns the corresponding value or <tt>#f</tt>
if there is none.
<tt>Environment-alist</tt> returns the entire environment as a list of
<tt>(<i>name-string</i> . <i>value-string</i>)</tt> pairs.</p>
<p>
</p>
<a name="node_sec_8.4"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.4">8.4&nbsp;&nbsp;Users and groups</a></h2>
<p><i>User-id</i>s and <i>group-id</i>s are boxed integers representing
Unix users and groups.
The procedures in this section are in structures <tt>posix-users</tt> and
<tt>posix</tt>.</p>
<p>
</p>
<ul>
<li><p><tt>(user-id?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_688"></a>
</p>
<li><p><tt>(user-id=?<i> user-id0 user-id1</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_690"></a>
</p>
<li><p><tt>(user-id-&gt;integer<i> user-id</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_692"></a>
</p>
<li><p><tt>(integer-&gt;user-id<i> integer</i>)&nbsp;-&gt;&nbsp;<i>user-id</i></tt><a name="node_idx_694"></a>
</p>
</ul><p></p>
<p>
</p>
<ul>
<li><p><tt>(group-id?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_696"></a>
</p>
<li><p><tt>(group-id=?<i> group-id0 group-id1</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_698"></a>
</p>
<li><p><tt>(group-id-&gt;integer<i> group-id</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_700"></a>
</p>
<li><p><tt>(integer-&gt;group-id<i> integer</i>)&nbsp;-&gt;&nbsp;<i>group-id</i></tt><a name="node_idx_702"></a>
</p>
</ul><p>
User-ids and group-ids have their own
own predicates and comparison, boxing, and unboxing functions.</p>
<p>
</p>
<ul>
<li><p><tt>(user-id-&gt;user-info<i> user-id</i>)&nbsp;-&gt;&nbsp;<i>user-info</i></tt><a name="node_idx_704"></a>
</p>
<li><p><tt>(name-&gt;user-info<i> string</i>)&nbsp;-&gt;&nbsp;<i>user-info</i></tt><a name="node_idx_706"></a>
</p>
</ul><p>
These return the user info for a user identified by user-id or name.</p>
<p>
</p>
<ul>
<li><p><tt>(user-info?<i> x</i>)&nbsp;-&gt;&nbsp;<i> boolean</i></tt><a name="node_idx_708"></a>
</p>
<li><p><tt>(user-info-name<i> user-info</i>)&nbsp;-&gt;&nbsp;<i> string</i></tt><a name="node_idx_710"></a>
</p>
<li><p><tt>(user-info-id<i> user-info</i>)&nbsp;-&gt;&nbsp;<i> user-id</i></tt><a name="node_idx_712"></a>
</p>
<li><p><tt>(user-info-group<i> user-info</i>)&nbsp;-&gt;&nbsp;<i> group-id</i></tt><a name="node_idx_714"></a>
</p>
<li><p><tt>(user-info-home-directory<i> user-info</i>)&nbsp;-&gt;&nbsp;<i> string</i></tt><a name="node_idx_716"></a>
</p>
<li><p><tt>(user-info-shell<i> user-info</i>)&nbsp;-&gt;&nbsp;<i> string</i></tt><a name="node_idx_718"></a>
</p>
</ul><p>
A <tt>user-info</tt> contains information about a user.
Available are the user's name, id, group, home directory, and shell.</p>
<p>
</p>
<ul>
<li><p><tt>(group-id-&gt;group-info<i> group-id</i>)&nbsp;-&gt;&nbsp;<i>group-info</i></tt><a name="node_idx_720"></a>
</p>
<li><p><tt>(name-&gt;group-info<i> string</i>)&nbsp;-&gt;&nbsp;<i>group-info</i></tt><a name="node_idx_722"></a>
</p>
</ul><p>
These return the group info for a group identified by group-id or name.</p>
<p>
</p>
<ul>
<li><p><tt>(group-info?<i> x</i>)&nbsp;-&gt;&nbsp;<i> boolean</i></tt><a name="node_idx_724"></a>
</p>
<li><p><tt>(group-info-name<i> group-info</i>)&nbsp;-&gt;&nbsp;<i> string</i></tt><a name="node_idx_726"></a>
</p>
<li><p><tt>(group-info-id<i> group-info</i>)&nbsp;-&gt;&nbsp;<i> group-id</i></tt><a name="node_idx_728"></a>
</p>
<li><p><tt>(group-info-members<i> group-info</i>)&nbsp;-&gt;&nbsp;<i> user-ids</i></tt><a name="node_idx_730"></a>
</p>
</ul><p>
A <tt>group-info</tt> contains information about a group.
Available are the group's name, id, and a list of members.</p>
<p>
</p>
<a name="node_sec_8.5"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.5">8.5&nbsp;&nbsp;OS and machine identification</a></h2>
<p>These procedures return strings that are supposed to identify the current
OS and machine.
The POSIX standard does not indicate the format of the strings.
The procedures are in structures <tt>posix-platform-names</tt> and <tt>posix</tt>.</p>
<p>
</p>
<ul>
<li><p><tt>(os-name<i></i>)&nbsp;-&gt;&nbsp;<i>string</i></tt><a name="node_idx_732"></a>
</p>
<li><p><tt>(os-node-name<i></i>)&nbsp;-&gt;&nbsp;<i>string</i></tt><a name="node_idx_734"></a>
</p>
<li><p><tt>(os-release-name<i></i>)&nbsp;-&gt;&nbsp;<i>string</i></tt><a name="node_idx_736"></a>
</p>
<li><p><tt>(os-version-name<i></i>)&nbsp;-&gt;&nbsp;<i>string</i></tt><a name="node_idx_738"></a>
</p>
<li><p><tt>(machine-name<i></i>)&nbsp;-&gt;&nbsp;<i>string</i></tt><a name="node_idx_740"></a>
</p>
</ul><p></p>
<p>
</p>
<p>
</p>
<a name="node_sec_8.6"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.6">8.6&nbsp;&nbsp;Files and directories</a></h2>
<p>These procedures are in structures <tt>posix-files</tt> and <tt>posix</tt>.</p>
<p>
</p>
<a name="node_sec_8.6.1"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.6.1">8.6.1&nbsp;&nbsp;Directory streams</a></h3>
<p>Directory streams are like input ports, with each read operation
returning the next name in the directory.</p>
<p>
</p>
<ul>
<li><p><tt>(open-directory-stream<i> name</i>)&nbsp;-&gt;&nbsp;<i>directory</i></tt><a name="node_idx_742"></a>
</p>
<li><p><tt>(directory-stream?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_744"></a>
</p>
<li><p><tt>(read-directory-stream<i> directory</i>)&nbsp;-&gt;&nbsp;<i>name or <tt>#f</tt></i></tt><a name="node_idx_746"></a>
</p>
<li><p><tt>(close-directory-stream<i> directory</i>)</tt><a name="node_idx_748"></a>
</p>
</ul><p>
<tt>Open-directory-stream</tt> opens a new directory stream.
<tt>Directory-stream?</tt> is a predicate that recognizes directory streams.
<tt>Read-directory-stream</tt> returns the next name in the directory or
<tt>#f</tt> if all names have been read.
<tt>Close-directory-stream</tt> closes a directory stream.</p>
<p>
</p>
<ul>
<li><p><tt>(list-directory<i> name</i>)&nbsp;-&gt;&nbsp;<i>list of strings</i></tt><a name="node_idx_750"></a>
</p>
</ul><p>
This is the obvious utility; it returns a list of the names in directory
<i>name</i>.</p>
<p>
</p>
<a name="node_sec_8.6.2"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.6.2">8.6.2&nbsp;&nbsp;Working directory</a></h3>
<p></p>
<ul>
<li><p><tt>(working-directory<i></i>)&nbsp;-&gt;&nbsp;<i>string</i></tt><a name="node_idx_752"></a>
</p>
<li><p><tt>(set-working-directory!<i> string</i>)</tt><a name="node_idx_754"></a>
</p>
</ul><p>
These return and set the working directory.</p>
<p>
</p>
<a name="node_sec_8.6.3"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.6.3">8.6.3&nbsp;&nbsp;File creation and removal</a></h3>
<p></p>
<ul>
<li><p><tt>(open-file<i> path file-options</i>)&nbsp;-&gt;&nbsp;<i>port</i></tt><a name="node_idx_756"></a>
</p>
<li><p><tt>(open-file<i> path file-options file-mode</i>)&nbsp;-&gt;&nbsp;<i>port</i></tt><a name="node_idx_758"></a>
</p>
</ul><p>
<tt>Open-file</tt> opens a port to the file named by string <i>path</i>.
The <i>file-options</i> argument determines various aspects of the 
returned port.
The optional <i>file-mode</i> argument is used only if the file to be opened
does not already exist.
The returned port is an input port if <i>file-options</i> includes
<tt>read-only</tt>; otherwise it returns an output port.
<tt>Dup-switching-mode</tt> can be used to open an input port for
output ports opened with the <tt>read/write</tt> option.</p>
<p>
</p>
<ul>
<li><p><tt>(file-options <i>file-option-name</i> <tt>...</tt>)&nbsp;-&gt;&nbsp;<i>file-options</i></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(syntax)
</p>
<li><p><tt>(file-options-on?<i> file-options file-options</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_760"></a>
</p>
<li><p><tt>(file-options-union<i> file-options file-options</i>)&nbsp;-&gt;&nbsp;<i>file-options</i></tt><a name="node_idx_762"></a>
</p>
</ul><p>
The syntax <tt>file-options</tt> returns a file-option with the
indicated options set.
<tt>File-options-on?</tt> returns true if its first argument includes all of
the options listed in the second argument.  <tt>File-options-union</tt>
returns a file-options argument containing exactly all of the options
listed in either argument.
The following file options may be used with <tt>open-file</tt>.</p>
<p>
</p>
<div align=center><table><tr><td>

<table border=0><tr><td valign=top ></td><td valign=top ><tt>create</tt> </td><td valign=top >create file if it does not already exist; a file-mode argument
is required with this option </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>exclusive</tt> </td><td valign=top >an error will be raised if this option and <tt>create</tt>
are both set and the file already exists </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>no-controlling-tty</tt> </td><td valign=top >if <i>path</i> is a terminal device this option
causes the terminal to not become the controlling terminal of the process</td></tr>
<tr><td valign=top ></td><td valign=top ><tt>truncate</tt> </td><td valign=top >file is truncated </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>append</tt> </td><td valign=top >writes are appended to existing contents </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>nonblocking</tt> </td><td valign=top >read and write operations do not block </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>read-only</tt> </td><td valign=top >port may not be written </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>read-write</tt> </td><td valign=top >file descriptor may be read or written </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>write-only</tt> </td><td valign=top >port may not be read
</td></tr></table>
</td></tr></table></div>

Only one of the last three options may be used.  If
<tt>read-write</tt> is specified, an output port is returned.<p>
For example
</p>
<pre class=verbatim>(open-file &quot;some-file.txt&quot;
           (file-options create write-only)
           (file-mode read owner-write))
</pre><p>
returns an output port that writes to a newly-created file that can be
read by anyone and written only by the owner.
Once the file exists,
</p>
<pre class=verbatim>(open-file &quot;some-file.txt&quot;
           (file-options append write-only))
</pre><p>
will open an output port that appends to the file.</p>
<p>
The <tt>append</tt> and <tt>nonblocking</tt> options and the read/write nature of
the port can be read using <tt>i/o-flags</tt>.
The <tt>append</tt> and <tt>nonblocking</tt> options can be set
using <tt>set-i/o-flags!</tt>.</p>
<p>
To keep port operations from blocking the Scheme&nbsp;48 process, output
ports are set to be nonblocking at the time of creation (input ports
are managed using <tt>select()</tt>).
You can use <tt>set-i/o-flags!</tt> to make an output port blocking, for
example just before a fork, but care should be exercised.
The Scheme&nbsp;48 runtime code may get confused if an I/O operation blocks.</p>
<p>
</p>
<ul>
<li><p><tt>(set-file-creation-mask!<i> file-mode</i>)</tt><a name="node_idx_764"></a>
</p>
</ul><p>
Sets the file creation mask to be <i>file-mode</i>.
Bits set in <i>file-mode</i> are cleared in the modes of any files or
directories created by the current process.</p>
<p>
</p>
<ul>
<li><p><tt>(link<i> existing new</i>)</tt><a name="node_idx_766"></a>
</p>
</ul><p>
<tt>Link</tt> makes path <i>new</i> be a new link to the file
pointed to by path <i>existing</i>.
The two paths must be in the same file system.</p>
<p>
</p>
<p>
</p>
<ul>
<li><p><tt>(make-directory<i> name file-mode</i>)</tt><a name="node_idx_768"></a>
</p>
<li><p><tt>(make-fifo<i> file-mode</i>)</tt><a name="node_idx_770"></a>
</p>
</ul><p>
These two procedures make new directories and fifo files.</p>
<p>
</p>
<p>
</p>
<ul>
<li><p><tt>(unlink<i> path</i>)</tt><a name="node_idx_772"></a>
</p>
<li><p><tt>(remove-directory<i> path</i>)</tt><a name="node_idx_774"></a>
</p>
<li><p><tt>(rename<i> old-path new-path</i>)</tt><a name="node_idx_776"></a>
</p>
</ul><p>
<tt>Unlink</tt> removes the link indicated by <i>path</i>.
<tt>Remove-directory</tt> removes the indicated (empty) directory.
<tt>Rename</tt> moves the file pointed to by <i>old-path</i> to the
location pointed to by <i>new-path</i> (the two paths must be in
the same file system).
Any other links to the file remain unchanged.</p>
<p>
</p>
<p>
</p>
<ul>
<li><p><tt>(accessible?<i> path access-mode . more-modes</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_778"></a>
</p>
<li><p><tt>(access-mode <i>mode-name</i>)&nbsp;-&gt;&nbsp;<i>access-mode</i></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(syntax)
</p>
</ul><p>
<tt>Accessible?</tt> returns true if <i>path</i> is a file that
can be accessed in the listed mode.
If more than one mode is specified <tt>accessible?</tt> returns true
if all of the specified modes are permitted.
The <i>mode-name</i>s are: <tt>read</tt>, <tt>write</tt>, <tt>execute</tt>,
<tt>exists</tt>.</p>
<p>
</p>
<a name="node_sec_8.6.4"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.6.4">8.6.4&nbsp;&nbsp;File information</a></h3>
<p></p>
<ul>
<li><p><tt>(get-file-info<i> name</i>)&nbsp;-&gt;&nbsp;<i>file-info</i></tt><a name="node_idx_780"></a>
</p>
<li><p><tt>(get-file/link-info<i> name</i>)&nbsp;-&gt;&nbsp;<i>file-info</i></tt><a name="node_idx_782"></a>
</p>
<li><p><tt>(get-port-info<i> fd-port</i>)&nbsp;-&gt;&nbsp;<i>file-info</i></tt><a name="node_idx_784"></a>
</p>
</ul><p>
<tt>Get-file-info</tt> and <tt>get-file/link-info</tt> both return
a file info record for the named file.
<tt>Get-file-info</tt> follows symbolic links while <tt>get-file/link-info</tt>
does not.
<tt>Get-port-info</tt> returns a file info record for the file
which <i>port</i> reads from or writes to.
An error is raised if <i>fd-port</i> does not read from or write to a
file descriptor.</p>
<p>
</p>
<ul>
<li><p><tt>(file-info?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_786"></a>
</p>
<li><p><tt>(file-info-name<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>string</i></tt><a name="node_idx_788"></a>
</p>
</ul><p>
<tt>File-info?</tt> is a predicate for file-info records.
<tt>File-info-name</tt> is the name which was used to get <tt>file-info</tt>,
either as passed to <tt>get-file-info</tt> or <tt>get-file/link-info</tt>,
or used to open the port passed to <tt>get-port-info</tt>.</p>
<p>
</p>
<ul>
<li><p><tt>(file-info-type<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>file-type</i></tt><a name="node_idx_790"></a>
</p>
<li><p><tt>(file-type?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_792"></a>
</p>
<li><p><tt>(file-type-name<i> file-type</i>)&nbsp;-&gt;&nbsp;<i>symbol</i></tt><a name="node_idx_794"></a>
</p>
<li><p><tt>(file-type <i>type</i>)&nbsp;-&gt;&nbsp;<i>file-type</i></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(syntax)
</p>
</ul><p>
<tt>File-info-type</tt> returns the type of the file, as a file-type object
File types may be compared using <tt>eq?</tt>.
The valid file types are:</p>
<p>
</p>
<div align=center><table><tr><td>

<table border=0><tr><td valign=top ><tt>regular</tt> </td></tr>
<tr><td valign=top ><tt>directory</tt> </td></tr>
<tr><td valign=top ><tt>character-device</tt> </td></tr>
<tr><td valign=top ><tt>block-device</tt> </td></tr>
<tr><td valign=top ><tt>fifo</tt> </td></tr>
<tr><td valign=top ><tt>symbolic-link</tt> </td></tr>
<tr><td valign=top ><tt>socket</tt> </td></tr>
<tr><td valign=top ><tt>other</tt>
</td></tr></table>
</td></tr></table></div>
<p>
<tt>Symbolic-link</tt> and <tt>socket</tt> are not required by POSIX.</p>
<p>
</p>
<ul>
<li><p><tt>(file-info-device<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_796"></a>
</p>
<li><p><tt>(file-info-inode<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_798"></a>
</p>
</ul><p>
The device and inode numbers uniquely determine a file.</p>
<p>
</p>
<ul>
<li><p><tt>(file-info-link-count<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_800"></a>
</p>
<li><p><tt>(file-info-size<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_802"></a>
</p>
</ul><p>
These return the number of links to a file and the file size in bytes.
The size is only meaningful for regular files.</p>
<p>
</p>
<ul>
<li><p><tt>(file-info-owner<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>user-id</i></tt><a name="node_idx_804"></a>
</p>
<li><p><tt>(file-info-group<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>group-id</i></tt><a name="node_idx_806"></a>
</p>
<li><p><tt>(file-info-mode<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>file-mode</i></tt><a name="node_idx_808"></a>
</p>
</ul><p>
These return the owner, group, and access mode of a file.</p>
<p>
</p>
<ul>
<li><p><tt>(file-info-last-access<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>time</i></tt><a name="node_idx_810"></a>
</p>
<li><p><tt>(file-info-last-modification<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>time</i></tt><a name="node_idx_812"></a>
</p>
<li><p><tt>(file-info-last-info-change<i> file-info</i>)&nbsp;-&gt;&nbsp;<i>time</i></tt><a name="node_idx_814"></a>
</p>
</ul><p>
These return the time the file was last read, modified, or had its
status modified</p>
<p>
</p>
<a name="node_sec_8.6.5"></a>
<h3><a href="manual-Z-H-2.html#node_toc_node_sec_8.6.5">8.6.5&nbsp;&nbsp;File modes</a></h3>
<p>A file mode is a boxed integer representing a file protection mask.</p>
<p>
</p>
<ul>
<li><p><tt>(file-mode permission-name <tt>...</tt>)&nbsp;-&gt;&nbsp;<i>file-mode</i></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(syntax)
</p>
<li><p><tt>(file-mode?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_816"></a>
</p>
<li><p><tt>(file-mode+<i> file-mode <tt>...</tt></i>)&nbsp;-&gt;&nbsp;<i>file-mode</i></tt><a name="node_idx_818"></a>
</p>
<li><p><tt>(file-mode-<i> file-mode0 file-mode1</i>)&nbsp;-&gt;&nbsp;<i>file-mode</i></tt><a name="node_idx_820"></a>
</p>
</ul><p>
<tt>File-mode</tt> is syntax for creating file modes.
The mode-names are listed below.
<tt>File-mode?</tt> is a predicate for file modes.
<tt>File-mode+</tt> returns a mode that contains all of permissions of
its arguments.
<tt>File-mode-</tt> returns a mode that has all of the permissions of
<i>file-mode0</i> that are not in <i>file-mode1</i>.</p>
<p>
</p>
<ul>
<li><p><tt>(file-mode=?<i> file-mode0 file-mode1</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_822"></a>
</p>
<li><p><tt>(file-mode&lt;=?<i> file-mode0 file-mode1</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_824"></a>
</p>
<li><p><tt>(file-mode&gt;=?<i> file-mode0 file-mode1</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_826"></a>
</p>
</ul><p>
<tt>File-mode=?</tt> returns true if the two modes are exactly the same.
<tt>File-mode&lt;=?</tt> returns true if <i>file-mode0</i> has a subset
of the permissions of <i>file-mode1</i>.
<tt>File-mode&gt;=?</tt> is <tt>file-mode&lt;=?</tt> with the arguments reversed.</p>
<p>
</p>
<ul>
<li><p><tt>(file-mode-&gt;integer<i> file-mode</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_828"></a>
</p>
<li><p><tt>(integer-&gt;file-mode<i> integer</i>)&nbsp;-&gt;&nbsp;<i>file-mode</i></tt><a name="node_idx_830"></a>
</p>
</ul><p>
<tt>Integer-&gt;file-mode</tt> and <tt>file-mode-&gt;integer</tt> translate file modes
to and from the classic Unix file mode masks.
These may not be the masks used by the underlying OS.</p>
<p>
</p>
<div align=center><table><tr><td>

<table border=0><tr><td valign=top >Permission name </td><td valign=top >Bit mask </td></tr>
<tr><td valign=top ><tt>set-uid</tt> </td><td valign=top ><tt>#o4000</tt> </td><td valign=top >set user id when executing </td></tr>
<tr><td valign=top ><tt>set-gid</tt> </td><td valign=top ><tt>#o2000</tt> </td><td valign=top >set group id when executing </td></tr>
<tr><td valign=top ><tt>owner-read</tt> </td><td valign=top ><tt>#o0400</tt> </td><td valign=top >read by owner </td></tr>
<tr><td valign=top ><tt>owner-write</tt> </td><td valign=top ><tt>#o0200</tt> </td><td valign=top >write by owner </td></tr>
<tr><td valign=top ><tt>owner-exec</tt> </td><td valign=top ><tt>#o0100</tt> </td><td valign=top >execute (or search) by owner </td></tr>
<tr><td valign=top ><tt>group-read</tt> </td><td valign=top ><tt>#o0040</tt> </td><td valign=top >read by group </td></tr>
<tr><td valign=top ><tt>group-write</tt> </td><td valign=top ><tt>#o0020</tt> </td><td valign=top >write by group </td></tr>
<tr><td valign=top ><tt>group-exec</tt> </td><td valign=top ><tt>#o0010</tt> </td><td valign=top >execute (or search) by group </td></tr>
<tr><td valign=top ><tt>other-read</tt> </td><td valign=top ><tt>#o0004</tt> </td><td valign=top >read by others </td></tr>
<tr><td valign=top ><tt>other-write</tt> </td><td valign=top ><tt>#o0002</tt> </td><td valign=top >write by others </td></tr>
<tr><td valign=top ><tt>other-exec</tt> </td><td valign=top ><tt>#o0001</tt> </td><td valign=top >execute (or search) by others </td></tr>
<tr><td valign=top ></td></tr></table>
</td></tr></table></div>
<p>
</p>
<div align=center><table><tr><td>

<table border=0><tr><td valign=top  colspan=3>Names for sets of permissions </td></tr>
<tr><td valign=top ><tt>owner</tt> </td><td valign=top ><tt>#o0700</tt> </td><td valign=top >read, write, and execute by owner </td></tr>
<tr><td valign=top ><tt>group</tt> </td><td valign=top ><tt>#o0070</tt> </td><td valign=top >read, write, and execute by group </td></tr>
<tr><td valign=top ><tt>other</tt> </td><td valign=top ><tt>#o0007</tt> </td><td valign=top >read, write, and execute by others </td></tr>
<tr><td valign=top ><tt>read</tt> </td><td valign=top ><tt>#o0444</tt> </td><td valign=top >read by anyone </td></tr>
<tr><td valign=top ><tt>write</tt> </td><td valign=top ><tt>#o0222</tt> </td><td valign=top >write by anyone </td></tr>
<tr><td valign=top ><tt>exec</tt> </td><td valign=top ><tt>#o0111</tt> </td><td valign=top >execute by anyone </td></tr>
<tr><td valign=top ><tt>all</tt> </td><td valign=top ><tt>#o0777</tt> </td><td valign=top >anything by anyone
</td></tr></table>
</td></tr></table></div>
<p>
</p>
<a name="node_sec_8.7"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.7">8.7&nbsp;&nbsp;Time</a></h2>
<p>These procedures are in structures <tt>posix-time</tt> and <tt>posix</tt>.</p>
<p>
</p>
<ul>
<li><p><tt>(make-time<i> integer</i>)&nbsp;-&gt;&nbsp;<i>time</i></tt><a name="node_idx_832"></a>
</p>
<li><p><tt>(current-time<i></i>)&nbsp;-&gt;&nbsp;<i>time</i></tt><a name="node_idx_834"></a>
</p>
<li><p><tt>(time?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_836"></a>
</p>
<li><p><tt>(time-seconds<i> time</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_838"></a>
</p>
</ul><p>
A <tt>time</tt> record contains an integer that represents time as
the number of second since the Unix epoch (00:00:00 GMT, January 1, 1970).
<tt>Make-time</tt> and <tt>current-time</tt> return <tt>time</tt>s, with
<tt>make-time</tt>'s using its argument while <tt>current-time</tt>'s has
the current time.
<tt>Time?</tt> is a predicate that recognizes <tt>time</tt>s and
<tt>time-seconds</tt> returns the number of seconds <i>time</i> represents.</p>
<p>
</p>
<ul>
<li><p><tt>(time=?<i> time time</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_840"></a>
</p>
<li><p><tt>(time&lt;?<i> time time</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_842"></a>
</p>
<li><p><tt>(time&lt;=?<i> time time</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_844"></a>
</p>
<li><p><tt>(time&gt;?<i> time time</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_846"></a>
</p>
<li><p><tt>(time&gt;=?<i> time time</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_848"></a>
</p>
</ul><p>
These perform various comparison operations on the <tt>time</tt>s.</p>
<p>
</p>
<ul>
<li><p><tt>(time-&gt;string<i> time</i>)&nbsp;-&gt;&nbsp;<i>string</i></tt><a name="node_idx_850"></a>
</p>
</ul><p>
<tt>Time-&gt;string</tt> returns a string representation of <i>time</i> in the
following form.
</p>
<pre class=verbatim>&quot;Wed Jun 30 21:49:08 1993
&quot;
</pre><p></p>
<p>
</p>
<p>
</p>
<a name="node_sec_8.8"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.8">8.8&nbsp;&nbsp;I/O</a></h2>
<p>These procedures are in structures <tt>posix-i/o</tt> and <tt>posix</tt>.</p>
<p>
</p>
<p>
</p>
<p>
</p>
<p>
</p>
<p>
</p>
<p>
</p>
<p>
</p>
<ul>
<li><p><tt>(open-pipe<i></i>)&nbsp;-&gt;&nbsp;<i>input-port + output-port</i></tt><a name="node_idx_852"></a>
</p>
</ul><p>
<tt>Open-pipe</tt> creates a new pipe and returns the two ends as an
input port and an output port.</p>
<p>
</p>
<p>
A <em>file descriptor</em> port (or <i>fd-port</i>)
is a port that reads to or writes from an OS file descriptor.
Fd-ports are returned by <tt>open-input-file</tt>, <tt>open-output-file</tt>,
<tt>open-file</tt>, <tt>open-pipe</tt>, and other procedures.
</p>
<p>
</p>
<ul>
<li><p><tt>(fd-port?<i> port</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_854"></a>
</p>
<li><p><tt>(port-&gt;fd<i> port</i>)&nbsp;-&gt;&nbsp;<i>integer or <tt>#f</tt></i></tt><a name="node_idx_856"></a>
</p>
</ul><p>
<tt>Fd-port?</tt> returns true if its argument is an fd-port.
<tt>Port-&gt;fd</tt> returns the file descriptor associated with 
or <tt>#f</tt> if <i>port</i> is not an fd-port.</p>
<p>
</p>
<ul>
<li><p><tt>(remap-file-descriptors<i> fd-spec <tt>...</tt></i>)</tt><a name="node_idx_858"></a>
</p>
</ul><p>
<tt>Remap-file-descriptors</tt> reassigns file descriptors to ports.
The <i>fd-specs</i> indicate which port is to be mapped to each
file descriptor: the first gets file descriptor <tt>0</tt>, the second gets
<tt>1</tt>, and so forth.
A <i>fd-spec</i> is either a port that reads from or writes to
a file descriptor,
or <tt>#f</tt>, with <tt>#f</tt> indicating that the corresponding file
descriptor is not used.
Any open ports not listed are marked `close-on-exec'.
The same port may be moved to multiple new file descriptors.</p>
<p>
For example,
</p>
<pre class=verbatim>(remap-file-descriptors (current-output-port)
                        #f
                        (current-input-port))
</pre><p>
moves the current output port to file descriptor <tt>0</tt> and the
current input port to file descriptor <tt>2</tt>.</p>
<p>
</p>
<ul>
<li><p><tt>(dup<i> fd-port</i>)&nbsp;-&gt;&nbsp;<i>fd-port</i></tt><a name="node_idx_860"></a>
</p>
<li><p><tt>(dup-switching-mode<i> fd-port</i>)&nbsp;-&gt;&nbsp;<i>fd-port</i></tt><a name="node_idx_862"></a>
</p>
<li><p><tt>(dup2<i> fd-port file-descriptor</i>)&nbsp;-&gt;&nbsp;<i>fd-port</i></tt><a name="node_idx_864"></a>
</p>
</ul><p>
These change <i>fd-port</i>'s file descriptor and return a new port
that uses <i>ports</i>'s old file descriptor.
<tt>Dup</tt> uses the lowest unused file descriptor and <tt>dup2</tt> uses the
one provided.
<tt>Dup-switching-mode</tt> is the same as <tt>dup</tt> except that the returned
port is an input port if the argument was an output port and vice
versa.
If any existing port uses the file descriptor passed to <tt>dup2</tt>, that
port is closed.</p>
<p>
</p>
<ul>
<li><p><tt>(close-all-but<i> port <tt>...</tt></i>)</tt><a name="node_idx_866"></a>
</p>
</ul><p>
<tt>Close-all-but</tt> closes all file descriptors whose associated ports
are not passed to it as arguments.</p>
<p>
</p>
<p>
</p>
<p>
</p>
<p>
</p>
<ul>
<li><p><tt>(close-on-exec?<i> port</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_868"></a>
</p>
<li><p><tt>(set-close-on-exec?!<i> port boolean</i>)</tt><a name="node_idx_870"></a>
</p>
</ul><p>
<tt>Close-on-exec?</tt> returns true if <tt>port</tt> will be closed
when a new program is exec'ed.
<tt>Set-close-on-exec?!</tt> sets <tt>port</tt>'s close-on-exec flag.</p>
<p>
</p>
<p>
</p>
<ul>
<li><p><tt>(i/o-flags<i> port</i>)&nbsp;-&gt;&nbsp;<i>file-options</i></tt><a name="node_idx_872"></a>
</p>
<li><p><tt>(set-i/o-flags!<i> port file-options</i>)</tt><a name="node_idx_874"></a>
</p>
</ul><p>
These two procedures read and write various options for <tt>port</tt>.
The options that can be read are <tt>append</tt>, <tt>nonblocking</tt>,
<tt>read-only</tt>, <tt>write-only</tt>, and <tt>read/write</tt>.
Only the <tt>append</tt> and <tt>nonblocking</tt> can be written.</p>
<p>
</p>
<p>
</p>
<p>
</p>
<ul>
<li><p><tt>(port-is-a-terminal?<i> port</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_876"></a>
</p>
<li><p><tt>(port-terminal-name<i> port</i>)&nbsp;-&gt;&nbsp;<i>string</i></tt><a name="node_idx_878"></a>
</p>
</ul><p>
<tt>Port-is-a-terminal?</tt> returns true if <i>port</i> has an underlying
file descriptor that is associated with a terminal.
For such ports <tt>port-terminal-name</tt> returns the name of the
terminal, for all others it returns <tt>#f</tt>.</p>
<p>
</p>
<p>
</p>
<a name="node_sec_8.9"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.9">8.9&nbsp;&nbsp;Regular expressions</a></h2>
<p></p>
<p>
The procedures in this section provide access to POSIX regular expression
matching.
The regular expression syntax and semantics are far too complex to
be described here.
Because the C interface uses zero bytes for marking the ends of strings,
patterns and strings that contain zero bytes will not work correctly.</p>
<p>
These procedures are in structures <tt>posix-regexps</tt> and <tt>posix</tt>.</p>
<p>
An abstract data type for creating POSIX regular expressions is
described in section&nbsp;<a href="manual-Z-H-7.html#node_sec_5.20">5.20</a>.</p>
<p>
</p>
<ul>
<li><p><tt>(make-regexp<i> string . regexp-options</i>)&nbsp;-&gt;&nbsp;<i>regexp</i></tt><a name="node_idx_880"></a>
</p>
<li><p><tt>(regexp-option <i>option-name</i>)&nbsp;-&gt;&nbsp;<i>regexp-option</i></tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(syntax)
</p>
</ul><p>
<tt>Make-regexp</tt> makes a new regular expression, using <i>string</i>
as the pattern.
The possible option names are:</p>
<p>
</p>
<div align=center><table><tr><td>

<table border=0><tr><td valign=top ><tt>extended</tt> </td><td valign=top >use the extended patterns </td></tr>
<tr><td valign=top ><tt>ignore-case</tt> </td><td valign=top >ignore case when matching </td></tr>
<tr><td valign=top ><tt>submatches</tt> </td><td valign=top >report submatches </td></tr>
<tr><td valign=top ><tt>newline</tt> </td><td valign=top >treat newlines specially 
</td></tr></table>
</td></tr></table></div>
<p>
The regular expression is not compiled until it matched against a string,
so any errors in the pattern string will not be reported until that
point.</p>
<p>
</p>
<ul>
<li><p><tt>(regexp?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_882"></a>
</p>
</ul><p>
This is a predicate for regular expressions.</p>
<p>
</p>
<ul>
<li><p><tt>(regexp-match<i> regexp string start submatches? starts-line? ends-line?</i>)</tt><a name="node_idx_884"></a>
<br>
<tt>    -&gt;&nbsp;<i>boolean or list of matches</i></tt>
</p>
<li><p><tt>(match?<i> x</i>)&nbsp;-&gt;&nbsp;<i>boolean</i></tt><a name="node_idx_886"></a>
</p>
<li><p><tt>(match-start<i> match</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_888"></a>
</p>
<li><p><tt>(match-end<i> match</i>)&nbsp;-&gt;&nbsp;<i>integer</i></tt><a name="node_idx_890"></a>
</p>
</ul><p>
<tt>Regexp-match</tt> matches the regular expression against the characters
in <i>string</i>, starting at position <i>start</i>.
If the string does not match the regular expression, <tt>regexp-match</tt>
returns <tt>#f</tt>.
If the string does match, then a list of match records is returned
if <i>submatches?</i> is true, or <tt>#t</tt> is returned if it is not.
Each match record contains the index of the character at the beginning
of the match and one more than the index of the character at the end.
The first match record gives the location of the substring that matched
<i>regexp</i>.
If the pattern in <i>regexp</i> contained submatches, then the results
of these are returned in order, with a match records reporting submatches
that succeeded and <tt>#f</tt> in place of those that did not.</p>
<p>
<i>Starts-line?</i> should be true if <i>string</i> starts at the beginning
of a line and <i>ends-line?</i> should be true if it ends one.</p>
<p>
</p>
<a name="node_sec_8.10"></a>
<h2><a href="manual-Z-H-2.html#node_toc_node_sec_8.10">8.10&nbsp;&nbsp;C to Scheme correspondence</a></h2>
<p></p>
<p>
The following table lists the Scheme procedures that correspond to
particular C procedures.
Not all of the Scheme procedures listed are part of the POSIX interface.</p>
<p>
</p>
<table border=0><tr><td valign=top >C procedure </td><td valign=top >Scheme procedure(s) </td></tr>
<tr><td valign=top >C procedure </td><td valign=top >Scheme procedure(s) </td></tr>
<tr><td valign=top ><tt>access</tt></td><td valign=top ><tt>accessible?</tt></td></tr>
<tr><td valign=top ><tt>chdir</tt></td><td valign=top ><tt>set-working-directory!</tt></td></tr>
<tr><td valign=top ><tt>close</tt></td><td valign=top ><tt>close-input-port, close-output-port,</tt></td></tr>
<tr><td valign=top ></td><td valign=top ><tt>  close-channel, close-socket</tt></td></tr>
<tr><td valign=top ><tt>closedir</tt></td><td valign=top ><tt>close-directory-stream</tt></td></tr>
<tr><td valign=top ><tt>creat</tt></td><td valign=top ><tt>open-file</tt></td></tr>
<tr><td valign=top ><tt>ctime</tt></td><td valign=top ><tt>time-&gt;string</tt></td></tr>
<tr><td valign=top ><tt>dup</tt></td><td valign=top ><tt>dup, dup-switching-mode</tt></td></tr>
<tr><td valign=top ><tt>dup2</tt></td><td valign=top ><tt>dup2</tt></td></tr>
<tr><td valign=top ><tt>exec[l|v][e|p|epsilon]</tt>
</td><td valign=top ><tt>exec, exec-with-environment,</tt> </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>  exec-file, exec-file-with-environment,</tt> </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>  exec-with-alias</tt></td></tr>
<tr><td valign=top ><tt>_exit</tt></td><td valign=top ><tt>exit</tt></td></tr>
<tr><td valign=top ><tt>fcntl</tt></td><td valign=top ><tt>io-flags, set-io-flags!,</tt></td></tr>
<tr><td valign=top ></td><td valign=top ><tt>  close-on-exec, set-close-on-exec!</tt></td></tr>
<tr><td valign=top ><tt>fork</tt></td><td valign=top ><tt>fork, fork-and-forget</tt></td></tr>
<tr><td valign=top ><tt>fstat</tt></td><td valign=top ><tt>get-port-info</tt></td></tr>
<tr><td valign=top ><tt>getcwd</tt></td><td valign=top ><tt>working-directory</tt></td></tr>
<tr><td valign=top ><tt>getegid</tt></td><td valign=top ><tt>get-effective-group-id</tt></td></tr>
<tr><td valign=top ><tt>getenv</tt></td><td valign=top ><tt>lookup-environment-variable,</tt> </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>  environment-alist</tt></td></tr>
<tr><td valign=top ><tt>geteuid</tt></td><td valign=top ><tt>get-effective-user-id</tt></td></tr>
<tr><td valign=top ><tt>getgid</tt></td><td valign=top ><tt>get-group-id</tt></td></tr>
<tr><td valign=top ><tt>getgroups</tt></td><td valign=top ><tt>get-groups</tt></td></tr>
<tr><td valign=top ><tt>getlogin</tt></td><td valign=top ><tt>get-login-name</tt></td></tr>
<tr><td valign=top ><tt>getpid</tt></td><td valign=top ><tt>get-process-id</tt></td></tr>
<tr><td valign=top ><tt>getppid</tt></td><td valign=top ><tt>get-parent-process-id</tt></td></tr>
<tr><td valign=top ><tt>getuid</tt></td><td valign=top ><tt>get-user-id</tt></td></tr>
<tr><td valign=top ><tt>isatty</tt></td><td valign=top ><tt>port-is-a-terminal?</tt></td></tr>
<tr><td valign=top ><tt>link</tt></td><td valign=top ><tt>link</tt></td></tr>
<tr><td valign=top ><tt>lstat</tt></td><td valign=top ><tt>get-file/link-info</tt></td></tr>
<tr><td valign=top ><tt>mkdir</tt></td><td valign=top ><tt>make-directory</tt></td></tr>
<tr><td valign=top ><tt>mkfifo</tt></td><td valign=top ><tt>make-fifo</tt></td></tr>
<tr><td valign=top ><tt>open</tt></td><td valign=top ><tt>open-file</tt></td></tr>
<tr><td valign=top ><tt>opendir</tt></td><td valign=top ><tt>open-directory-stream</tt></td></tr>
<tr><td valign=top ><tt>pipe</tt></td><td valign=top ><tt>open-pipe</tt></td></tr>
<tr><td valign=top ><tt>read</tt></td><td valign=top ><tt>read-char, read-block</tt></td></tr>
<tr><td valign=top ><tt>readdir</tt></td><td valign=top ><tt>read-directory-stream</tt></td></tr>
<tr><td valign=top ><tt>rename</tt></td><td valign=top ><tt>rename</tt></td></tr>
<tr><td valign=top ><tt>rmdir</tt></td><td valign=top ><tt>remove-directory</tt></td></tr>
<tr><td valign=top ><tt>setgid</tt></td><td valign=top ><tt>set-group-id!</tt></td></tr>
<tr><td valign=top ><tt>setuid</tt></td><td valign=top ><tt>set-user-id!</tt></td></tr>
<tr><td valign=top ><tt>stat</tt></td><td valign=top ><tt>get-file-info</tt></td></tr>
<tr><td valign=top ><tt>time</tt></td><td valign=top ><tt>current-time</tt></td></tr>
<tr><td valign=top ><tt>ttyname</tt></td><td valign=top ><tt>port-terminal-name</tt></td></tr>
<tr><td valign=top ><tt>umask</tt></td><td valign=top ><tt>set-file-creation-mask!</tt></td></tr>
<tr><td valign=top ><tt>uname</tt></td><td valign=top ><tt>os-name, os-node-name,</tt> </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>  os-release-name, os-version-name,</tt> </td></tr>
<tr><td valign=top ></td><td valign=top ><tt>  machine-name</tt></td></tr>
<tr><td valign=top ><tt>unlink</tt></td><td valign=top ><tt>unlink</tt></td></tr>
<tr><td valign=top ><tt>waitpid</tt></td><td valign=top ><tt>wait-for-child-process</tt></td></tr>
<tr><td valign=top ><tt>write</tt></td><td valign=top ><tt>write-char, write-block</tt></td></tr>
<tr><td valign=top ></td></tr></table><p>


</p>
<div align=right class=navigation><i>[Go to <span><a href="manual.html">first</a>, <a href="manual-Z-H-9.html">previous</a></span><span>, <a href="manual-Z-H-11.html">next</a></span> page<span>; &nbsp;&nbsp;</span><span><a href="manual-Z-H-2.html#node_toc_start">contents</a></span><span><span>; &nbsp;&nbsp;</span><a href="manual-Z-H-13.html#node_index_start">index</a></span>]</i></div>
<p></p>
</div>
</body>
</html>
